home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / a86v302a.arc / 03OPREQ.DOC < prev    next >
Text File  |  1987-04-24  |  9KB  |  205 lines
  1. CHAPTER 3   OPERATION AND REQUIREMENTS                    3-1
  2.  
  3.  
  4. A86 Program Invocation
  5.  
  6. To invoke A86, you must provide a program invocation line, either 
  7. typed to the console when the DOS command prompt appears, or 
  8. included in a batch file.  The program invocation line consists 
  9. of the following: 
  10.  
  11. 1. The program name A86.
  12.  
  13. 2. The names of the source files you want to assemble.  You may 
  14.    use the wild-card delimiters * and ? if you wish, to denote a 
  15.    group of source files to be assembled.  A86 will sort all 
  16.    matching names into alphabetical order for each wild-card 
  17.    specification; so the files will be assembled in the same 
  18.    order even if they get jumbled up within a directory.  
  19.  
  20.    A86 identifies the end of the source file names when it sees a 
  21.    name with no extension, or a name with the default object-
  22.    extension.  That extension is .COM, unless you have assembled 
  23.    an ORG 0 statement; in which case the default extension is 
  24.    .OBJ. Sorry, you cannot have a source file with the default 
  25.    object extension.  
  26.  
  27. 3. You may optionally provide the word TO, to separate the source 
  28.    file names from the output file names.  
  29.  
  30. 4. The name of the output program.  If you do not provide an 
  31.    extension, A86 will assume one of the following extensions:
  32.  
  33.      a. .OBJ if you invoked the +O switch, for linkable-object
  34.         file production.
  35.  
  36.      b. .BIN if there is no +O switch, but there is an ORG 0 in 
  37.         your program.
  38.  
  39.      c. .COM otherwise.
  40.  
  41.    If you want your program file to have no extension, you end 
  42.    the file name with a period.  
  43.  
  44.    You have the option to omit both the program file name and the 
  45.    symbol table file name from the invocation.  If you do so, A86 
  46.    will output the program source.COM (or source.OBJ or 
  47.    source.BIN) and the symbol table source.SYM; where "source" is 
  48.    a name derived from the list of source files, according to the 
  49.    rules described in the section "Strategies for Source File 
  50.    Maintenance" below.  
  51.  
  52. 5. The name of the symbol-table file.  If you do not provide an 
  53.    extension, A86 will assume that you want the extension .SYM.  
  54.    If you want your symbol table file to have no extension, you 
  55.    end the file name with a period.  
  56.                                                           3-2
  57.    You have the option to omit the name of the symbol table file.  
  58.    If you do so, A86 will use the same root as the output program 
  59.    name, with a .SYM extension.  If you desire no symbol table 
  60.    file, specify the +S switch in your invocation line or A86 
  61.    environment variable.
  62.  
  63.  
  64. Assembler Switches
  65.  
  66. In addition to input and output file names, you may intersperse 
  67. assembler switch-settings anywhere after the A86 program name.  
  68. They are all acted upon immediately, no matter where they are on 
  69. the command line. Some of the switches are discussed in more 
  70. detail elsewhere; we summarize them here: 
  71.  
  72. +C  causes the assembler to be sensitive to upper- vs. lower-case
  73.     for all symbols, so that routines with lower-case names can 
  74.     be created for linking to C programs.  WARNING: I provide 
  75.     only limited support for this right now.  In particular, if 
  76.     you use this option, you MUST give all built-in symbol names 
  77.     in ALL CAPS.  And D86 doesn't recognize this yet-- although 
  78.     D86 will correctly disassemble symbols containing lower-case 
  79.     letters, you won't be able to refer to such symbols in D86 
  80.     commands, because D86 will convert your references to all-
  81.     upper-case.
  82.  
  83. -C  causes A86 to ignore upper- vs. lower-case in all symbol 
  84.     names.
  85.  
  86. +D  causes the default base for numeric constants to be decimal, 
  87.     even if the constants have leading zeroes.
  88.  
  89. -D  causes the default base to be hexadecimal if there is a 
  90.     leading zero; decimal otherwise.
  91.  
  92. +E  causes the error-message-augmented source file to be written 
  93.     to yourname.ERR within the current directory, in all cases.  
  94.     With +E, A86 will never rewrite your original source file. 
  95.  
  96. -E  causes A86 to insert error messages into your source file,
  97.     whenever the file is in the current directory.  If the file 
  98.     is not in the current directory, A86 write an ERR file no 
  99.     matter what the E-switch setting is.
  100.  
  101. +L  causes A86 to generate a longer (3-byte) instruction form 
  102.     for an unconditional JMP instruction to a forward-reference 
  103.     local labels, e.g. JMP >L1.  The code will usually be longer 
  104.     than necessary, but you'll be spared having to occasionally 
  105.     go back and code an explicit JMP LONG >L1.
  106.  
  107. -L  causes A86 to generate the more efficient 2-byte form for
  108.     JMP >L1.
  109.  
  110. +O  causes A86 to produce a linkable .OBJ file when the output 
  111.     file name extension is not explicitly given.
  112.  
  113. -O  causes A86 to produce an executable .COM file when the output 
  114.     file name extension is not explicitly given.
  115.                                                           3-3
  116. +S  suppresses the creation of the symbol-table (.SYM) file in 
  117.     normal (no errors) assembly.  This is overridden if you give 
  118.     an explicit symbols-file name in the invocation line.
  119.  
  120. -S  causes the symbol-table file to be created in all cases.
  121.  
  122. +X  causes A86 to require that undefined names be explicitly 
  123.     declared with an EXTRN when A86 is producing a linkable .OBJ 
  124.     file.  The X switch has no effect when A86 is making a .COM 
  125.     file.
  126.  
  127. -X  causes A86 to quietly assume that all undefined names are 
  128.     valid external references.
  129.     
  130. The default setting for all the switches is "minus".  Multiple 
  131. switches can be specified with a single sign; e.g. +OX is the 
  132. same as +O+X.
  133.  
  134. Switch settings can also be declared in the environment variable 
  135. A86.  For example, of you execute the command SET A86=+OX while 
  136. in DOS (typically in the AUTOEXEC.BAT file run when the computer 
  137. is started), then the O and X switches will be "plus", unless 
  138. overridden with a "minus" setting in the command line.             
  139.  
  140.  
  141. Strategies for Source File Maintenance
  142.  
  143. A86 encourages modular programming, by letting you break your 
  144. source into separate files, with complete impunity.  A86 has no 
  145. concern whatsoever for file breaks-- it treats the sequence of 
  146. files as a single source code stream.  
  147.  
  148. You should consider one or more of the following strategies, 
  149. which I have adopted in my source file management: 
  150.  
  151. 1. I name all my A86 source files with the same extension, which 
  152.    is found on no other files. The particular extension I have 
  153.    chosen is ".8". I did not choose the more common .ASM; because 
  154.    I have a few source-files designed for MSDOS's assembler.  If 
  155.    you don't like .8, I would suggest .A86.  
  156.  
  157. 2. I keep a separate sub-directory on my hard disk for each 
  158.    multi-source-file A86 program I have.  Then the simple command 
  159.    "A86 *.8" performs the assembly for the current directory's 
  160.    program.  
  161.  
  162. 3. I exploit the fact that A86 expands wild-cards into 
  163.    alphabetical order.  Whenever I want a source-file to be 
  164.    assembled first (e.g., when it contains variable 
  165.    declarations), I append a decimal digit to the start of the 
  166.    file name: 0 for the first file, 1 for the second, etc., for 
  167.    however many files that need to be explicitly ordered.  If a 
  168.    file needs to come last, I append a "Z" to the start of the 
  169.    file name.  
  170.                                                           3-4
  171.    To accommodate this strategy, I have programmed A86 to a 
  172.    somewhat complicated algorithm for determining the default 
  173.    output file-name.  I use the name of the first source file; 
  174.    but I truncate the first character if it is a decimal digit.  
  175.    However, you may have a general-purpose file that must come 
  176.    first; so I have provided the following exception: if you have 
  177.    a source-file whose name begins with the digit "9", that name 
  178.    (without the 9) is used.  If you don't like this, you can 
  179.    always explicitly give the program name you want: "A86 *.8 
  180.    MYPROG".  
  181.  
  182.  
  183. System Requirements for A86
  184.  
  185. A86 requires MS-DOS V2.00 or later.  No BIOS or lower-level calls 
  186. are made by A86, so A86 should run on any MS-DOS machine.  Please 
  187. let me know if you find this not to be the case.  
  188.  
  189. To achieve its blazing speed, A86 is something of a memory hog. 
  190. A86 allocates separate segments for itself, its stack, its source 
  191. file, and its output file.  A86 itself now occupies about 22K; it 
  192. always takes a full 64K for the stack.  A86 splits the remaining 
  193. available memory between its source file and its output file.  It 
  194. allocates a minimum of 8K apiece; and a maximum of 64K apiece.   
  195. Thus A86 requires at least 102K; but it will consume up to 214K if 
  196. available.  
  197.  
  198. Careful reading of the above paragraph reveals that in a small-
  199. memory system A86 severely limits the size of source files.  But 
  200. remember that this doesn't hurt you badly: you can split up 
  201. source files with impunity.  A86 assembles a sequence of files as 
  202. if it were a single source stream (similar to the INCLUDE 
  203. facility of other assemblers).  
  204.  
  205.